fix(hooks): guard-main-checkout reads the path key its routed tool carries - #7686

Fixes #7260

What was wrong

.claude/settings.json routes Edit|Write|NotebookEdit at this hook, and the hook extracted
exactly one key, .tool_input.file_path. NotebookEdit does not carry that key — its path
key is notebook_path. Verified against the tool's own documented input schema rather than
assumed: notebook_path (absolute, required) and new_source (required), plus cell_id,
cell_type, edit_mode; there is no file_path anywhere in a NotebookEdit payload.

So every notebook edit produced an empty path, fell into the no-path branch and was judged by
CLAUDE_PROJECT_DIR instead of by the file being written. The jq-less fallback grepped for
the same single key, so it missed it too. The resulting verdict is a constant per session,
wrong in both directions depending only on where the session happens to be rooted: notebook
edits inside a correctly created worktree were refused, and notebook edits into the shared
primary checkout were waved through.

The fix

The hook now carries one tool-to-path-key table and reads the key the routed tool actually
carries, in the jq path and in the text-scan fallback alike:

known_path_keys='Edit=file_path Write=file_path MultiEdit=file_path NotebookEdit=notebook_path'

• A tool the table names is read for its own key.
• A tool the table does not name is not routed here by the matcher, so it keeps today's
  permissive read: any known key it happens to carry, else the project-dir fallback.
• A tool the table does name that carries no path under its own key is schema drift,
  not a missing path. It blocks (exit 2) with a message naming the tool and the key it wanted,
  instead of silently falling back to a verdict about the session. That was the seat's ruling
  on the frame's contract-tightening axis: tolerance here is exactly what hides the error.

The matcher and the table are now a checked relation

This was triage's acceptance condition — "a tool listed in the matcher" and "a path key the
extractor knows" must be a checkable relation, not one more //. The self-test's wiring
section reads known_path_keys out of the hook, splits the matcher on |, and asserts every
routed tool has a row:

  ok   pair   Edit          -> .tool_input.file_path
  ok   pair   Write         -> .tool_input.file_path
  ok   pair   NotebookEdit  -> .tool_input.notebook_path
  note       MultiEdit has a row in known_path_keys; the matcher does not route it

A row with no matcher entry is the harmless direction and prints a note. A tool routed here
with no row is a failure — so the next tool routed at this hook cannot repeat this defect
silently, which was the whole point of not just adding one more key.

Before to after: the notebook rows

The known-hole section flips to the intended verdicts and its banner is gone. PROJ is
CLAUDE_PROJECT_DIR; every row points it somewhere that would give the wrong answer under a
session-based verdict, so a passing row can only have come from the notebook's own path.

Rows that were pinned as INTENDED and that this change flips

Per the ruling: a row pinned as intended behaviour (not under a known-hole banner) that
contradicts the drift rule gets flipped, listed, and explained. Three places:

1. tool_name=NotebookEdit into $WT was allow, now block. That row fed a
   file_path-carrying payload under the name NotebookEdit. Under the fix that is a routed
   tool with no path under its own key, i.e. drift. The section's premise — "tool_name is
   never consulted" — is itself falsified by the fix (tool_name now selects the key, though
   the verdict still comes from the path alone), so the section was rewritten rather than
   patched, and it now covers Edit/Write/MultiEdit by file_path, NotebookEdit by
   notebook_path, and an unrouted tool through both keys.
2. no usable path, CLAUDE_PROJECT_DIR=$WT and =$PLAIN for the probe
   {"tool_name":"Edit","tool_input":{}} were allow, now block. Routed tool, no path
   under its key: drift, so the session's root no longer decides.
3. The CLAUDE_PROJECT_DIR unset section's probe was re-pointed, not flipped. It exists
   to measure the cwd fallback, and that branch still exists for unrouted payloads, so its
   probe is now an unrouted AnythingElse and its three verdicts are unchanged. The routed
   Edit probe moved into the new drift section, where it is asserted as block under all
   three roots.

The remaining known hole in the matrix — the */worktrees/* substring predicate — is
untouched, banner and all.

Self-test counts

Run against the old matrix, the new hook produces exactly 9 failures — the 9 rows listed
above and nothing else, in both repos. No unlisted row changed.

The jq-less fallback is exercised, not assumed: the matrix runs the notebook rows, the drift
row and the decoy rows a second time with jq removed from PATH (the existing nojq
fixture), because a fallback that still reads one key sends notebook edits straight back to
the no-path branch whenever jq is away.

Non-vacuity

Each new class was driven red against a mutated copy of the hook (GUARD_MAIN_CHECKOUT_HOOK
points the matrix at it, so the tree is never mutated and there is no restore leg to get
wrong). Each mutation was proved on disk by grepping for the injected and the removed text
before the matrix was run, and the hook blob in the worktree was checked equal to its HEAD
blob. Identical results in both repos:

Cross-repo convergence

The two hooks' executable lines are byte-identical before and after. Diff of the two files
after this change, comments stripped: empty. Full diff, comments included:

106,113d105
< # (the 8-line comment block about the worktree recipe that the objectstack copy already carried)

That is the same eight comment lines the objectstack copy carried before this change, and no
executable line differs. The self-tests differ only where they already did: objectui's porting
header, and the remaining known hole's issue reference pointing at each repo's own card.

Exclusions

• .claude/settings.json — untouched (the matcher is not changed).
• the */worktrees/* predicate and its known-hole section — untouched.
• guard-main-checkout-bash.sh — untouched; it parses .tool_input.command and never sees
  notebook payloads.

Sibling PR carrying the byte-identical executable diff:
objectstack-ai/objectstack branch claude/issue-11810-guard-hook-notebook-path for
objectstack#11810. The two repos move together, as triage required.

Gates

This repo has no dispatch-gates derivation, so the family was found by asking which check
scripts read .claude: grep -l '\.claude' scripts/*.mjs, cross-read against the check:*
scripts in package.json. Exit codes captured by redirecting first, never across a pipe.

check-skill-examples.mjs exits 2 with the example program was NOT run: the packages it resolves against are not built, and its own source declares
export const SCAN_ROOTS = ['skills', '.claude/skills']. This change set is
.claude/hooks/** — outside both scan roots — so building the ten package closures its
--build-filter names would measure the same tree as main. Recorded as NOT MEASURED with
that reason; CI runs it regardless.

Changeset

This repo has no skip-changeset label, so scripts/check-changeset-presence.mjs decides,
and it was run:

Compared the working tree with a472b0716 (merge-base with origin/main): 2 file(s) changed,
0 of them published source of a package the release covers, 0 of them a manifest whose
published contract moved, 0 under a package changesets ignores, 0 changeset(s) added.
✅  No source or published contract of a released package changed in this range, so no
changeset is owed.

No changeset added, per that verdict.

pnpm lint — NOT MEASURED, by eslint's own configuration, not by a choice of mine.
Asked directly about the two changed files, eslint answers per file:

File ignored because no matching configuration was supplied.

Both changed files are shell, outside eslint's configured surface entirely, so this diff
cannot move any verdict about a file eslint does lint. In the sibling repo the same shell
surface is covered by check:bash32-floor (green over 27 files, .claude/hooks/** among its
scan roots); this repo has no equivalent shell gate, which is a gap worth its own card rather
than something to fix here.

Generated by Claude Code

Generated by Claude Code